\chapter{MULgraph geometry file format}
\label{geometry_file_format}
\index{MULgraph geometry!file format}

\section{Introduction}
This appendix gives a format specification of the MULgraph geometry file. These files can be used to give a geometrical description of a TOUGH2 model grid, useful for creating grids and visualizing simulation results.

MULgraph geometry files were originally developed for use with MULgraph, a graphical post-processor for TOUGH2 and AUTOUGH2 \citep{mulgraph} developed at the University of Auckland in the 1990s. However, MULgraph geometry files can be used independently of MULgraph. PyTOUGH is able to represent the contents of a MULgraph geometry file in a Python script via the \hyperref[mulgrids]{\texttt{mulgrid}} class.

\section{Grid structure}
\index{MULgraph geometry!grid structure}

\subsection{Layers and columns}
\index{MULgraph geometry!layers}
\index{MULgraph geometry!columns}
MULgraph geometry files implicitly assume a layered structure, with blocks arranged in layers and columns, and the same arrangement of columns in each layer. The only exception to this is at the top surface of the model, where layers are allowed to be incomplete (i.e. not contain all columns) in order to represent topography.

The layers are always of constant vertical thickness. However, the blocks in the top layer are allowed to vary in height, again to represent variations in ground surface elevation.

\subsection{Atmosphere blocks}
\index{MULgraph geometry!blocks!atmosphere}
The blocks in the top layer may optionally be connected to the atmosphere- either a single atmosphere block connected to all columns, or a separate atmosphere block over each column (see section \ref{geometry_format_conventions}).

\subsection{Tilted geometries}
\index{MULgraph geometry!tilting}
It is possible to tilt the geometry coordinate axes with respect to the vertical, to represent non-horizontal geometries. When a TOUGH2 grid is created from such a tilted geometry, only the gravity cosines of the grid connections are affected.

\subsection{Rotating permeability directions}
\index{MULgraph geometry!permeability directions}
It is also possible to rotate the permeability principal directions with respect to the coordinate axes- for example, to align permeabilities with a dominant fault direction. When a TOUGH2 grid is created, this can change the permeability index associated with each connection.

\section{Geometry types}
\index{MULgraph geometry!geometry type}
The original MULgraph file specification allowed for three types of geometry: `general', `rectangular' and `radial'. Only the `general' geometry type is supported by PyTOUGH. It is intended for representing general grids with arbitrary, possibly unstructured horizontal column arrangements.

The `rectangular' type was a special type for grids with rectangular horizontal column structures. These can also be represented using the `general' geometry type. Since PyTOUGH contains \hyperref[sec:mulgrid:rectangular]{methods} for constructing rectangular grids within the `general' geometry type, there is usually no longer any significant benefit from using the `rectangular' type.

The `radial' type was intended for grids with radial horizontal column structure. PyTOUGH also contains \hyperref[sec:t2grid:radial]{methods} for creating radial TOUGH2 grids. Simulation results from radial models can also be visualized using a simple one- or two-dimensional rectangular `general' geometry to represent the grid structure in the radial direction.

\section{Naming conventions and atmosphere types}
\label{geometry_format_conventions}
\index{MULgraph geometry!blocks!naming convention}
\index{MULgraph geometry!columns!naming convention}
\index{MULgraph geometry!nodes!naming convention}
\index{MULgraph geometry!layers!naming convention}
\index{MULgraph geometry!atmosphere type}

The grid block naming convention and atmosphere type used in a MULgraph geometry file are both integers which can be given the value 0, 1 or 2.  The meanings of these values are shown in Table \ref{tb:mulgrid_conventions} and \ref{tb:mulgrid_atmosphere_types}.

Note that the grid nodes (vertices) are also named according to the column part of the block naming convention. If naming nodes, columns or layers manually, while the names can in principle be arbitrary (within the naming convention), it is safest to right-justify them.

The MULgraph block naming conventions all use part of the block name to indicate the layer, and part of it to indicate the column. In PyTOUGH, it is also possible to use MULgraph geometry files in conjunction with TOUGH2 grids that follow other naming conventions, by means of a \hyperref[sec:mulgrid:blockmappings]{block mapping} dictionary.

\begin{table}[h]
  \begin{center}
    \begin{tabular}{|l|p{85mm}|}
      \hline
      0 & 3 characters for column followed by 2 digits for layer \\
      1 & 3 characters for layer followed by 2 digits for column \\
      2 & 2 characters for layer followed by 3 digits for column \\
      \hline
    \end{tabular}
    \caption{MULgraph geometry file naming conventions}
    \label{tb:mulgrid_conventions}
  \end{center}
\end{table}

\begin{table}[h]
  \begin{center}
    \begin{tabular}{|l|p{85mm}|}
      \hline
      0 & A single atmosphere block \\
      1 & One atmosphere block over each column \\
      2 & No atmosphere blocks \\
      \hline
    \end{tabular}
    \caption{MULgraph geometry file atmosphere types}
    \label{tb:mulgrid_atmosphere_types}
  \end{center}
\end{table}

\section{File format}
MUlgraph geometry files are simple formatted ASCII text files with a header line at the top, followed by a number of sections. Each section begins with a keyword and ends with a blank line. Each line has \textbf{fixed} format, so the different values have to be specified in the right text columns.

If you use PyTOUGH scripts to create and manipulate your grid geometries, you don't need to know anything about the format of a MULgraph geometry file, because PyTOUGH will handle reading and writing them for you. If, however, for some reason you do need to know how these files are structured, the format specification for a `general' type geometry file is given below.

\subsection{Header}
\index{MULgraph geometry!header}

This is a single line containing a number of global parameters of the geometry. Its format is given in table \ref{tb:mulgraph_format_header}.

Note that the block ordering parameter is an extension to the original MULgraph file format.

\begin{table}
  \begin{center}
    \begin{tabular}{|p{20mm}|l|l|l|p{50mm}|}
      \hline
      \textbf{Name} & \textbf{Type} & \textbf{Length} & \textbf{Columns} & \textbf{Description}\\
      \hline
      \textbf{Geometry type} & character & 5 & 1--5 & `GENER' for general geometry type; `RECTA' or `RADIA' for other types (but these are not supported by PyTOUGH)\\
      \hline
      \textbf{Naming convention} & integer & 1 & 6 & Block naming convention: see table \ref{tb:mulgrid_conventions}\\
      \hline
      \textbf{Atmosphere type} & integer & 1 & 7 & Type of atmosphere: see table \ref{tb:mulgrid_atmosphere_types}\\
      \hline
      \textbf{Atmosphere volume} & float & 10 & 8--17 & Volume of each atmosphere block (default $10^{20} m^3$)\\
      \hline
      \textbf{Atmosphere connection distance} & float & 10 & 18--27 & Connection distance for each atmosphere block (default $10^{-6} m$) \\
      \hline
      \textbf{Length unit} & character & 5 & 28--32 & Default is metres (blank); for feet specify `FEET'\\
      \hline
      \textbf{x-direction cosine} & float & 10 & 33--42 & Cosine of angle between x-axis and gravity vector (default zero); set positive for tilt in the x-direction\\
      \hline
      \textbf{y-direction cosine} & float & 10 & 43--52 & Cosine of angle between y-axis and gravity vector (default zero); set positive for tilt in the y-direction\\
      \hline
      \textbf{Connection type} & integer & 1 & 53 & Method of calculating connection parameters (default zero)- not supported by PyTOUGH\\
      \hline
      \textbf{Permeability angle} & float & 10 & 54--63 & Horizontal angle (degrees anti-clockwise) between first permeability direction and x-axis\\
      \hline
      \textbf{Block ordering} & integer & 2 & 64--65 & Block ordering scheme: 0 for original MULgraph layer/column ordering; 1 for PETSc DMPlex ordering (sorted by block type)\\
      \hline
    \end{tabular}
    \caption{MULgraph geometry file header line format}
    \label{tb:mulgraph_format_header}
  \end{center}
\end{table}

\subsection{Vertices}
\index{MULgraph geometry!nodes!format}
This section defines the horizontal locations of the grid vertices (nodes), at the corners of the columns. The first line just contains the keyword `VERTI'. Each subsequent line defines the position of a vertex, and has the format given in table \ref{tb:mulgraph_format_vertices}. The vertices section is terminated by a blank line.

\begin{table}
  \begin{center}
    \begin{tabular}{|p{20mm}|l|l|l|p{50mm}|}
      \hline
      \textbf{Name} & \textbf{Type} & \textbf{Length} & \textbf{Columns} & \textbf{Description}\\
      \hline
      \textbf{Vertex name} & character & 3 & 1--3 & Name of the vertex (honouring the \hyperref[tb:mulgrid_conventions]{column naming convention})\\
      \hline
      \textbf{x} & float & 10 & 4--13 & x-coordinate of the vertex\\
      \hline
      \textbf{y} & float & 10 & 14--23 & y-coordinate of the vertex\\
      \hline
    \end{tabular}
    \caption{MULgraph geometry file vertices format}
    \label{tb:mulgraph_format_vertices}
  \end{center}
\end{table}

\subsection{Grid}
\index{MULgraph geometry!columns!format}
This section specifies the vertices making up each column. The first line just contains the keyword `GRID'.

For each grid column, there is then a sub-header line with information about the column, followed by a line for each vertex making up the column. The sub-header line has the format given in table \ref{tb:mulgraph_format_column_header}, and the line for each vertex has the format given in table \ref{tb:mulgraph_format_column_vertex}. There are no blank lines between the definitions of the grid columns, but there is a blank line at the end of the section.

\begin{table}[h]
  \begin{center}
    \begin{tabular}{|p{20mm}|l|l|l|p{50mm}|}
      \hline
      \textbf{Name} & \textbf{Type} & \textbf{Length} & \textbf{Columns} & \textbf{Description}\\
      \hline
      \textbf{Column name} & character & 3 & 1--3 & Name of the column (honouring the \hyperref[tb:mulgrid_conventions]{column naming convention})\\
      \hline
      \textbf{Centre specified} & integer & 1 & 4--5 & Set non-zero to specify the column centre location, or zero (default) to calculate it as the centroid of the column\\
      \hline
      \textbf{Number of vertices} & integer & 2 & 6--7 & Number of vertices in the column\\
      \hline
      \textbf{Column centre x} & float & 10 & 8--17 & x-coordinate of column centre\\
      \hline
      \textbf{Column centre y} & float & 10 & 18--27 & y-coordinate of column centre\\
      \hline
    \end{tabular}
    \caption{MULgraph geometry file column header format}
    \label{tb:mulgraph_format_column_header}
  \end{center}
\end{table}

\begin{table}[h]
  \begin{center}
    \begin{tabular}{|p{20mm}|l|l|l|p{50mm}|}
      \hline
      \textbf{Name} & \textbf{Type} & \textbf{Length} & \textbf{Columns} & \textbf{Description}\\
      \hline
      \textbf{Vertex name} & character & 3 & 1--3 & Name of the vertex, as specified in the vertices section\\
      \hline
    \end{tabular}
    \caption{MULgraph geometry file column vertex format}
    \label{tb:mulgraph_format_column_vertex}
  \end{center}
\end{table}

\subsection{Connections}
\index{MULgraph geometry!connections!format}
This section defines the horizontal connections between columns. The first line just contains the keyword `CONNE'.

Each subsequent line defines a connection between two columns, and has the format given in table \ref{tb:mulgraph_format_connection}. There is a blank line at the end of the section.

\begin{table}[h]
  \begin{center}
    \begin{tabular}{|p{20mm}|l|l|l|p{50mm}|}
      \hline
      \textbf{Name} & \textbf{Type} & \textbf{Length} & \textbf{Columns} & \textbf{Description}\\
      \hline
      \textbf{First column name} & character & 3 & 1--3 & Name of the first column\\
      \hline
      \textbf{Second column name} & character & 3 & 4--6 & Name of the second column\\
      \hline
    \end{tabular}
    \caption{MULgraph geometry file connection format}
    \label{tb:mulgraph_format_connection}
  \end{center}
\end{table}

\subsection{Layers}
\index{MULgraph geometry!layers!format}
This section defines the grid layers. The first line just contains the keyword `LAYER'.

Each subsequent line defines a layer, with format given by table \ref{tb:mulgraph_format_layer}. There are no blank lines between layers, but there is a blank line at the end of the section.

\begin{table}[h]
  \begin{center}
    \begin{tabular}{|p{20mm}|l|l|l|p{50mm}|}
      \hline
      \textbf{Name} & \textbf{Type} & \textbf{Length} & \textbf{Columns} & \textbf{Description}\\
      \hline
      \textbf{Layer name} & character & 3 & 1--3 & Name of the layer (honouring the \hyperref[tb:mulgrid_conventions]{layer naming convention})\\
      \hline
      \textbf{Bottom elevation} & float & 10 & 4--13 & Elevation of the bottom of the layer\\
      \hline
      \textbf{Centre elevation} & float & 10 & 14--23 & Elevation of the centre of the layer\\
      \hline
    \end{tabular}
    \caption{MULgraph geometry file layer format}
    \label{tb:mulgraph_format_layer}
  \end{center}
\end{table}

\subsection{Surface elevation}
\index{MULgraph geometry!columns!surface elevation}
This section is optional, and can be used to define the surface elevation at any or all columns in the grid, to represent topography. The first line just contains the keyword `SURFA'.

Each subsequent line defines the surface elevation at a column, with format given by table \ref{tb:mulgraph_format_surface}. There is a blank line at the end of the section.

\begin{table}[h]
  \begin{center}
    \begin{tabular}{|p{20mm}|l|l|l|p{50mm}|}
      \hline
      \textbf{Name} & \textbf{Type} & \textbf{Length} & \textbf{Columns} & \textbf{Description}\\
      \hline
      \textbf{Column name} & character & 3 & 1--3 & Name of the column\\
      \hline
      \textbf{Surface elevation} & float & 10 & 4--13 & Surface elevation of the column\\
      \hline
    \end{tabular}
    \caption{MULgraph geometry file surface elevation format}
    \label{tb:mulgraph_format_surface}
  \end{center}
\end{table}

\subsection{Wells}
\index{MULgraph geometry!wells!format}
This section is optional, and can be used to define the positions of wells (including their tracks) within the geometry. Deviated wells are supported. The first line of the section just contains the keyword `WELLS'.

Each subsequent line defines the location of one point on a well track, with format given by table \ref{tb:mulgraph_format_wells}. At least two points are required to define each well (one for the wellhead and one for the bottom), with more than two points needed to define a deviated well. There is a blank line at the end of the section.

\begin{table}[h]
  \begin{center}
    \begin{tabular}{|p{20mm}|l|l|l|p{50mm}|}
      \hline
      \textbf{Name} & \textbf{Type} & \textbf{Length} & \textbf{Columns} & \textbf{Description}\\
      \hline
      \textbf{Well name} & character & 5 & 1--5 & Name of the well\\
      \hline
      \textbf{x} & float & 10 & 6--15 & x-coordinate of the well location\\
      \hline
      \textbf{y} & float & 10 & 16--25 & y-coordinate of the well location\\
      \hline
      \textbf{z} & float & 10 & 26--35 & z-coordinate of the well location\\
      \hline
    \end{tabular}
    \caption{MULgraph geometry file well format}
    \label{tb:mulgraph_format_wells}
  \end{center}
\end{table}

